Thanks for this PR! The min_distance feature for filtering out results below a distance threshold in large-limit queries is a useful addition. Here is a summary of the review:

Overall assessment: The implementation is well-structured and follows the existing code patterns. The parameter is plumbed consistently through the search stack (HGraph → HNSW → BasicSearcher/ParallelSearcher). The default value of std::numeric_limits<float>::lowest() ensures backward compatibility.

Key concerns:

1. [suggestion] iter_ctx replay path in hnswalg.cpp searchBaseLayerST: When replaying discard nodes from a previous iteration, min_distance is not checked. This is inconsistent with the entry-point and neighbor-visit paths.

2. [suggestion] lower_bound in hnswalg.cpp searchBaseLayerST: When the entry point is valid but filtered out by min_distance, lower_bound remains at float::max(), which may cause the search to explore more nodes than necessary. Consider setting lower_bound to dist regardless for pruning purposes.

3. [note] Brute-force fallback: The bruteForce method and searchRange interface do not receive min_distance. If these code paths are exercised with min_distance set, results will not be filtered.

4. [note] Edge case: Very large min_distance values could cause floating-point overflow in the min_distance + THRESHOLD_ERROR check.

Overall the changes look correct and the approach is sound. The suggestions above are non-blocking improvements for consistency and edge-case handling.

[suggestion] The entry point in parallel_searcher.cpp (around line 179) is missing the min_distance check. In basic_searcher.cpp, the entry point push to top_candidates is guarded by dist > inner_search_param.min_distance + THRESHOLD_ERROR, but in parallel_searcher.cpp the check is absent:

// parallel_searcher.cpp, entry point handling
if (check_func(ep)) {
    top_candidates->Push(dist, ep);  // no min_distance check
    lower_bound = top_candidates->Top().first;
}

This means when parallel_search_thread_count > 1, the entry point will always be added to top_candidates regardless of min_distance, which is inconsistent with the single-threaded path in basic_searcher.cpp. Consider adding the same guard:

if (check_func(ep) && dist > inner_search_param.min_distance + THRESHOLD_ERROR) {
    top_candidates->Push(dist, ep);
    lower_bound = top_candidates->Top().first;
}

Code review for PR #2408: support min_distance for large limit query

Issues Found

1. [suggestion] parallel_searcher.cpp:179 — Entry point missing min_distance check

The entry point in parallel_searcher.cpp is pushed to top_candidates without checking min_distance:

if (check_func(ep)) {
    top_candidates->Push(dist, ep);
    lower_bound = top_candidates->Top().first;
}

In contrast, basic_searcher.cpp applies the min_distance filter at its entry point (line 210 in the new code):

if ((not is_id_allowed || is_id_allowed->CheckValid(ep)) and
    dist > inner_search_param.min_distance + THRESHOLD_ERROR) {

This means the parallel searcher may return results with dist <= min_distance when the entry point itself is the best candidate.

2. [suggestion] hnswalg.cpp:1868-1872 — searchRange() does not pass min_distance to searchBaseLayerST

The searchRange public method calls searchBaseLayerST without passing min_distance:

top_candidates = searchBaseLayerST<false, true>(currObj, query_data, radius, ef, is_id_allowed);

This means range search completely ignores the min_distance parameter. If min_distance filtering is intended for range search as well (the range-search overload of searchBaseLayerST already accepts the parameter), searchRange should pass it through.

3. [note] hnswalg.cpp:690 — Range search lower_bound set to dist even when entry point filtered by min_distance

In the range-search overload of searchBaseLayerST, lower_bound is unconditionally set to dist before the min_distance check:

lower_bound = dist;
if (dist <= radius + THRESHOLD_ERROR && dist > min_distance + THRESHOLD_ERROR)
    top_candidates.emplace(dist, ep_id);

This is actually correct behavior for this overload — lower_bound reflects the actual search frontier distance, not the filtered frontier. This is consistent with the range-search semantics. However, it differs from the first overload (with iter_ctx) where lower_bound is only set when the entry point passes the min_distance filter, which was already noted by another reviewer.

Code review for PR #2408: support min_distance for large limit query.

This is a follow-up review. LHT129 already posted 6 comments on 2026-07-28 covering several issues that remain unresolved. I found one additional issue below.

New finding: ParallelSearcher entry point missing min_distance check

In src/impl/searcher/parallel_searcher.cpp line 179-181, the entry point is added to top_candidates without checking min_distance:

if (check_func(ep)) {
    top_candidates->Push(dist, ep);
    lower_bound = top_candidates->Top().first;
}

Compare with BasicSearcher::search_impl (basic_searcher.cpp line 210-211) which correctly applies the filter:

if ((not is_id_allowed || is_id_allowed->CheckValid(ep)) and
    dist > inner_search_param.min_distance + THRESHOLD_ERROR) {

This inconsistency means the parallel search path will return results below min_distance when the entry point happens to be close to the query. The fix is to add the same min_distance check to the parallel searcher entry point.

Previously reported issues (from LHT129, still unresolved):

1. hnswalg.cpp:558-559 — iter_ctx discard node replay does not check min_distance
2. hnswalg.cpp:566-573 — lower_bound stays at max() when entry point is filtered by min_distance, potentially causing excessive search exploration
3. algorithm_interface.h:63 — bruteForce and searchRange methods do not receive min_distance parameter

[suggestion] The is_last_filter path in searchKnn (around line 1716-1722 in hnswalg.cpp) is missing a min_distance check.

When iter_ctx != nullptr && !iter_ctx->IsFirstUsed() && is_last_filter, the function directly dumps all discard nodes from iter_ctx into the result without filtering by min_distance:

if (is_last_filter) {
    while (!iter_ctx->Empty()) {
        uint32_t cur_inner_id = iter_ctx->GetTopID();
        float cur_dist = iter_ctx->GetTopDist();
        result.emplace(cur_dist, getExternalLabel(cur_inner_id));  // no min_distance check
        iter_ctx->PopDiscard();
    }
    return result;
}

This is inconsistent with every other code path that applies the min_distance filter (entry point, neighbor visit in searchBaseLayerST, and both basic_searcher/parallel_searcher paths). Consider adding:

if (cur_dist > min_distance + vsag::THRESHOLD_ERROR) {
    result.emplace(cur_dist, getExternalLabel(cur_inner_id));
}

This ensures the min_distance filter is consistently applied across all search paths, including the final iteration of a multi-step filtered search.

I've reviewed this PR in addition to the existing 8 review comments from LHT129. Here is one additional finding:

[suggestion] parallel_searcher.cpp entry point missing min_distance filter

The entry point handling in parallel_searcher.cpp (around line 183 in the search_impl with label_table) does not apply the min_distance filter, unlike basic_searcher.cpp (label_table overload at line 384) which was updated to check dist > inner_search_param.min_distance + THRESHOLD_ERROR. This means in the parallel search path, the entry point will always be added to top_candidates regardless of min_distance, creating an inconsistency between the two searcher implementations.

Current code in parallel_searcher.cpp:

if (check_func(ep)) {
    top_candidates->Push(dist, ep);
    lower_bound = top_candidates->Top().first;
}

Suggested fix:

if (check_func(ep) && dist > inner_search_param.min_distance + THRESHOLD_ERROR) {
    top_candidates->Push(dist, ep);
    lower_bound = top_candidates->Top().first;
}

This is the same pattern already applied in basic_searcher.cpp and should be consistently applied across both searcher implementations.

[suggestion] Found two additional locations where the min_distance filter is missing:

1. src/impl/searcher/parallel_searcher.cpp line 179 — entry point missing min_distance check

The entry point push to top_candidates at line 179-180 is missing the min_distance check. This is inconsistent with the same pattern in basic_searcher.cpp (line 387-388), which correctly applies dist > inner_search_param.min_distance + THRESHOLD_ERROR before pushing the entry point.

When the entry point distance is <= min_distance + THRESHOLD_ERROR, it should not be added to top_candidates. Additionally, lower_bound should still be set to dist for search pruning purposes (same concern as in hnswalg.cpp line 572 and basic_searcher.cpp line 211).

Suggested fix:

if (check_func(ep) && dist > inner_search_param.min_distance + THRESHOLD_ERROR) {
    top_candidates->Push(dist, ep);
    lower_bound = top_candidates->Top().first;
}

2. src/algorithm/hnswlib/hnswalg.cpp line 1715-1722 — is_last_filter fast path missing min_distance check

In the is_last_filter fast path of searchKnn, discard nodes from iter_ctx are directly emplaced into result without applying the min_distance filter. This means when is_last_filter is true, results with distance <= min_distance will incorrectly appear in the final output.

The is_last_filter path is used when the last filter in a chain is reached, and results are returned directly without further graph search. The min_distance filter should be applied here consistently with other paths.

Suggested fix:

if (is_last_filter) {
    while (!iter_ctx->Empty()) {
        uint32_t cur_inner_id = iter_ctx->GetTopID();
        float cur_dist = iter_ctx->GetTopDist();
        if (cur_dist > min_distance + vsag::THRESHOLD_ERROR) {
            result.emplace(cur_dist, getExternalLabel(cur_inner_id));
        }
        iter_ctx->PopDiscard();
    }
    return result;
}

Additional Review Notes

[suggestion] Missing min_distance check in HGraph is_last_filter path

In src/algorithm/hgraph/hgraph_search.cpp, the is_last_filter fast path in HGraph::KnnSearch (around lines 154-160 in the original code) pushes all discard nodes from iter_filter_ctx directly into search_result without filtering by min_distance:

if (is_last_filter) {
    while (!iter_filter_ctx->Empty()) {
        uint32_t cur_inner_id = iter_filter_ctx->GetTopID();
        float cur_dist = iter_filter_ctx->GetTopDist();
        search_result->Push(cur_dist, cur_inner_id);  // no min_distance check
        iter_filter_ctx->PopDiscard();
    }
}

This is the same issue previously flagged for hnswalg.cpp's searchKnn is_last_filter path. Both the HGraph and HNSW is_last_filter paths should consistently apply the min_distance filter:

if (cur_dist > params.min_distance + THRESHOLD_ERROR) {
    search_result->Push(cur_dist, cur_inner_id);
}

Overall this is a well-structured PR that adds min_distance filtering support across the search pipeline. The parameter is plumbed consistently through HNSW, HGraph, and the searcher layers, with sensible defaults that make it a no-op when not configured.

The existing inline comments have covered the key concerns:

1. lower_bound pruning: When the entry point is filtered by min_distance, lower_bound remains at std::numeric_limits<float>::max(), causing unnecessary graph exploration. This affects hnswalg.cpp, basic_searcher.cpp, and parallel_searcher.cpp.
2. Missing min_distance in bruteForce/searchRange paths: The brute-force fallback in HGraph and the searchRange interface do not receive min_distance.
3. Missing tests: No test coverage for the new feature.
4. is_last_filter paths: The discard-node replay in searchKnn and KnnSearch is_last_filter paths do not apply min_distance filtering.

The core implementation logic (filtering results by distance threshold) is correct. The main area for improvement is ensuring lower_bound reflects the actual search frontier for pruning purposes, independent of result filtering.

I found one additional issue not covered by the existing comments:

[suggestion] hgraph_search.cpp KnnSearch is_last_filter path lacks min_distance check

Similar to the issue flagged in hnswalg.cpp:1704, the is_last_filter fast-path in HGraph::KnnSearch (around the while (!iter_filter_ctx->Empty()) loop) does not apply min_distance filtering. When is_last_filter is true, all remaining candidates from iter_filter_ctx are pushed into search_result unconditionally, bypassing the min_distance threshold. Results with dist <= min_distance that should be skipped will still appear in the output.

The fix should add a min_distance check before search_result->Push() in this path, consistent with the fix needed in hnswalg.cpp.

Additional review findings for the min_distance feature:

1. hgraph_search.cpp is_last_filter path (line 125): The is_last_filter fast-path in HGraph::KnnSearch (iterator overload) collects discard nodes from iter_filter_ctx and pushes them directly into search_result without checking min_distance. This is the same issue as the is_last_filter path in hnswalg.cpp:1704 — results with distance <= min_distance will be returned to the user in the last filter iteration.

2. hgraph_search.cpp brute_force_search (line 290): When brute_force_threshold triggers the brute-force fallback in SearchWithRequest, min_distance is not applied to filter results. The brute_force_search method does not accept or use min_distance, so results below the threshold will not be filtered when the brute-force path is taken. This is the HGraph counterpart of the bruteForce gap noted in the algorithm_interface.h comment.